QuickTime Music Architecture

Note-Related Data Structures

A note channel is analogous to a sound channel in that you allocate it, issue commands to it to produce sound, and close it when you're done. To specify details about the note channel, you use a data structure called a NoteRequest (see Listing 0-1 ).

Listing 1 Note-related data structures



 
struct NoteRequest {

    NoteRequestInfo   info;      // in post-QuickTime 2.0 only

    ToneDescription   tone;

};



struct NoteRequestInfo {

    UInt8       flags;

    UInt8       reserved;

    short       polyphony;

    Fixed       typicalPolyphony;

};



struct ToneDescription {

    OSType      synthesizerType;

    Str31       synthesizerName;

    Str31       instrumentName;

    long        instrumentNumber;

    long        gmNumber;

};

The next two fields specify the probable polyphony that the note channel will be used for. Polyphony means, literally, many sounds. A polyphony of 5 means that five notes can be playing simultaneously. The polyphony field enables QTMA to make sure that the allocated note channel can play all the notes you need. The typical polyphony field is a fixed-point number that should be set to the average number of voices the note channel will play; it may be whole or fractional. Some music components use this field to adjust the mixing level for a good volume. If in doubt, set the typical polyphony field to 0X00010000.

The ToneDescription structure is used throughout QTMA to specify a musical instrument sound in a device-independent fashion. This structure's synthesizerType and synthesizerName fields can request a particular synthesizer to play notes on. Usually, they're set to 0, meaning "choose the best General MIDI synthesizer." The gmNumber field indicates the General MIDI (GM) instrument or drum kit sound, which may be any of 135 such sounds supported by many synthesizer manufacturers. (All these sounds are available on a General MIDI Sound Module.) The GM instruments are numbered 1 through 128, and the seven drum kits are numbered 16385 and higher. For synthesizers that accept sounds outside the GM library, you can use the instrumentName and instrumentNumber fields to specify some other sound.